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Secure Boot 


For Batocera v39 and higher on x86_64 systems, streamlined support for Secure Boot is present. This 
makes it easier to boot Batocera on PCs which have poor secure boot key management in the native 
UEFI BIOS. The process detailed below will install Batocera's security certificate into the machine's 
“Machine Owner Keys” (MOK) into the PC's UEFI variable store. This will allow the machine to execute 
Batocera's bootloader, which has been digitally signed with Batocera's certificate, even when Secure 
Boot is enabled in the BIOS. 


Modifying Secure Boot and related settings may trip a “tamper switch” (Platform 
Configuration Register, PCR) in the system's Trusted Platform Module (TPM). Once the 
switch has been tripped, it cannot be reset without providing a recovery key. If BitLocker 
MPA, Disk Encryption is enabled, Windows will detect the tampering and will ask for the 
EY BitLocker recovery key before allowing Windows to boot. 


If the system is managed by someone else (such as your employer), recovery may 
require assistance from an authorized system administrator. Act responsibly, and only 
install Batocera on systems you own and manage. 


Before proceeding, make a copy of the required BitLocker recovery keys. Documentation on locating 
the keys can be found at 
https://support.microsoft.com/en-us/windows/where-to-look-for-your-bitlocker-recovery-key-fd2b3501- 
a4b9-61e9-f5e6-2a545ad77b3e 


Technical references: 


https://learn.microsoft.com/en-us/windows/security/hardware-security/tpm/switch-pcr-banks-on-tpm-2 
-0-devices 


https://www.dell.com/support/kbdoc/en-us/000124361/bitlocker-is-prompting-for-a-recovery-key-and-y 
ou-cannot-locate-the-key 


For Batocera v38 and lower, the keys must be enrolled by the BIOS itself (if available, 
otherwise just use legacy/CSM boot). This usually can be done from the security options 
of the BIOS. Search for an option which allows you to “Add keys”, “Generate keys from 
EFI file” or “Enroll Efi image”. The file to be selected, if asked, is 
EFI/boot/bootx64.efi. 


i 
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Security 


[Disabled] 


Remove ‘UEFI cA from DB 
> Restore DB defaults 


| Platform Keu(Pki | e62] 1| Test (AMD 
b Key ange Sy sik | acer 1| 


tos 
í ‘1 267 | Mixed 
ol O| No Keys 
ol 01 No Keys 


This method can be used instead of using the MOK management tool as explained below. 
Batocera v38 and lower does not have the MOK management tool installed. 


Prerequisites 


e The system must be an Intel/AMD system that supports booting in 64-bit UEFI mode, with the 
standard Microsoft signing key certificates. 

e Secure Boot must be enabled during the setup process. If offered the option to select the mode 
of Secure Boot to use, the “Standard” mode is recommended. Other modes are untested. 

e The UEFI BIOS firmware must support booting from the desired installation media type, and it 
must be possible to select which drive to boot while using UEFI. 

e A keyboard is required to navigate the MOK management procedure detailed below. 


As some of this configuration is vendor-specific, consult the manual for the machine before getting 
started. 


Preparation 


Flash Batocera on a drive, or upgrade an existing installation to v38 or higher. Attach the drive to 
your computer. 
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Configuration Steps 


Power on the computer and enter its BIOS setup or boot manager. Set the UEFI boot to the drive 
Batocera is installed on. The details of how to do this vary by manufacturer. On some systems there is 
a “boot manager” accessible by a keystroke at boot; on others the “boot order” bust be configured 
with the Batocera drive set first. Tom's Hardware has a good guide on Hov 
. For my demonstration run on my Dell laptop, | pressed [F12] at startup to enter the boot menu, 
used the arrow keys to navigate to the USB media, and hit [ENTER] to boot. 


Boot mode is set to: UEFI; Secure Boot: ON 


UEFI BOOT: 
r€FiInd Boot Manager 
r€FInd Boot Manager (direct) 
ubuntu 
Windows Boot Manager 


OTHER OPTIONS: 
BIOS Setup 
BIOS Flash Update 
Diagnostics 
SupportAssist OS Recovery 
Exit Boot Menu and Cont inue 


A blue screen will appear with a message Error Verification Failed (0x1A) Security Violation. Hit 
[ENTER] on the keyboard to continue. 


On the Shim UEFI key management screen, hit any key before the ten-second timer expires. 
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On the Perform MOK management screen, use the arrow keys to navigate to Enroll key from 
disk, and hit [ENTER]. 


i 


a 


On the Select Key screen, navigate to the BATOCERA partition and hit [ENTER]. 
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On the second Select Key screen, navigate to the 
ENROLL_THIS_KEY_IN MOKMANAGER batocera.cer certificate file, and hit [ENTER]. 


a ü O 


| ENROLL _THIS_KEY_IN_MOKMANAGER_batocer 


On the Enroll MOK screen, navigate to the Continue menu item, and hit [ENTER]. 
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| Cont inue f 


On the Enroll the key(s)? screen, navigate to the Yes menu item, and hit [ENTER]. 


L OE 


On the second Perform MOK management screen, hit [ENTER] to reboot the system. 
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The system will reboot. If the system's TPM is enabled, proceed to the next section, otherwise it 
should automatically launch Batocera with Secure Boot enabled. 


If other operating system disks are attached to the system, they can be selected for boot from your 
firmware's boot menu. The ef ibootmgr command-line utility in Batocera can also be used to adjust 


boot order, or to perform a one-time “boot-next” to another UEFI OS. Os Fix Mel this 


commentary needs to move elsewhere) 


TPM 


Batocera's Secure Boot support requires some interaction between the bootloader and the system's 
hardware Trusted Platform Module (TPM), even on systems where Secure Boot is not enabled. 


If the system's TPM is enabled, the first time you boot into the newer Batocera versions, and after 
completing the Secure Boot MOK management setup (if Secure Boot is enabled), a Boot Option 
Restoration screen with a countdown will be displayed. If no action is taken, the system will reboot 
repeatedly into this screen. 
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Using a keyboard, press any key to move on to the next screen. 


On the Boot Options Restored screen, use the arrow keys to select Always continue boot and 
press [Enter]. The system will then boot into Batocera. 


| Aluweys continue boot f 


It will be necessary to perform this setup only once, as long as the correct option is selected. 


Upgrading and Downgrading with Secure 
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Boot 


It is safe to upgrade to later Batocera versions while Secure Boot is enabled. Downgrading to v39 or 
higher is also safe. If the newly upgraded/downgraded version was signed with a different signing key 
certificate which is not already enrolled, the MOK enrollment process may be reappear. It is possible 
to avoid this by disabling Secure Boot validation in the shim. 


If Batocera is downgraded to v38 or lower, the system may fail to boot in Secure Boot mode from the 
bootloaders installed by those versions. On systems where Secure Boot can be disabled, disabling it 
should allow the system to boot again. It is recommended to disable Secure Boot before such a 
downgrade. 


EFI bootloader entry may allow the earlier versions to boot with Secure Boot enabled. 


ey After the downgrade, the Secure Boot capable bootloader referenced in the Batocera 
Whether this works or not will depend on the system's specific UEFI BIOS behaviors. 


Disabling Secure Boot validation in the shim 


Once Secure Boot is set up and working, it is possible to leave Secure Boot enabled in the system, 
while disabling Secure Boot verification in the shim. This is optional, and is riskier than the normal 
setup allowing only signed bootloader components to run. 


To disable Secure Boot verification, SSH into Batocera and run the following: 
mokutil --disable-validation 
To re-enable Secure Boot verification: 
mokutil --enable-validation 


The mokutil command will request a (one-time) password. It is strongly recommended that you use 
the password 12345678 as the password for the validation state change, reasons for which will be 
explained below. 


Reboot the system, and the MOK Manager will ask to allow changing the verification state. It will then 
request a few random characters of the password by specifying the position number of the desired 
character. For example, if it asks for character #2, type 2 and press [ENTER]. Repeat the process 
until the MOK manager is satisfied, then select the reboot option to restart the system with the new 
validation state. 
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